
/*! \page quickstart Quickstart Guide
 * 
 * \htmlonly <script type="text/javascript">var randomUser1=Math.floor(Math.random()*1000000);var randomUser2=Math.floor(Math.random()*1000000);</script> \endhtmlonly
 * 
 * \section download Download
 * 
 * If you haven't already downloaded Acquire, to get Acquire,
 * you can download the source tarball, and extract
 * it with:
 * 
 * <p> <tt>tar -xvjf acquire_*.tar.bz2</tt><p>
 * 
 * or you can clone the latest development branch from the
 * repository into a new 'acquire-source' directory
 * with:
 * 
 * <p> <tt>svn checkout
 * http://acquire.googlecode.com/svn/branches/devel
 * acquire-source</tt><p>
 * 
 * \section install Building and Installation
 * 
 * Make sure that the prerequisites installed first before you begin
 * building. To run Acquire, you will need:<p><tt> <a
 * href="http://apr.apache.org/">libapr1</a> >= 0.21&nbsp;</tt>(the Apache
 * Portable Runtime layer library)<tt><br> <a
 * href="http://apr.apache.org/">libaprutil1</a>&nbsp;</tt>(utilities
 * for the Apache Portable Runtime)<tt><br> <a
 * href="http://www.libssh2.org/">libssh2</a> >= 1.2&nbsp;</tt>(an SSH
 * protocol client library)<tt><br> <a
 * href="http://www.openssl.org/">openssl</a>&nbsp;</tt>(the Secure
 * Sockets Library, used for cryptography)<tt><br> <a
 * href="http://www.python.org/">python</a>&nbsp;</tt>(the Python
 * language interpreter)<p> To build Acquire, you will additionally
 * need a C compiler (gcc) with C++ support, and:<p><tt> <a
 * href="http://www.gnu.org/software/binutils/">binutils</a>&nbsp;</tt>(utilities
 * for maipulating ELF binaries)<tt><br> <a
 * href="http://www.cmake.org/">cmake</a>&nbsp;</tt>(cross platform
 * Make, similar to <a href="http://www.gnu.org/software/make/">GNU
 * Make</a>)<tt><br> <a
 * href="http://www.swig.org/">swig</a>&nbsp;</tt>(Simplified Wrapper
 * and Interface Generator, for the Python interface)<br><p> When
 * building in an environment that uses a packaging system, you should
 * also install development packages for:<p><tt> <a
 * href="http://apr.apache.org/">libapr1-dev</a>&nbsp;</tt>(development
 * files for the Apache Portable Runtime layer library)<tt><br> <a
 * href="http://apr.apache.org/">libaprutil1-dev</a>&nbsp;</tt>(development
 * file for the Apache Portable Runtime utilities)<tt><br> <a
 * href="http://www.libssh2.org/">libssh2-dev</a> >=
 * 1.2&nbsp;</tt>(development files for the SSH protocol client
 * library)<tt><br> <a
 * href="http://www.openssl.org/">openssl-dev</a>&nbsp;</tt>(development
 * files for the Secure Sockets Library, used for
 * cryptography)<tt><br> <a
 * href="http://www.python.org/">python-dev</a>&nbsp;</tt>(development
 * files for the Python language interpreter)<tt><br> <a
 * href="http://valgrind.org/">valgrind</a>&nbsp;</tt>(analysis tools
 * for development, <i>optional</i>)<p> Also, <tt><a
 * href="http://www.doxygen.org/">doxygen</a></tt> if documentation
 * regeneration is required.
 * 
 * \subsection generatebuilddir Preparing to Build 
 * 
 * Create a separate build directory from the source 
 * for building with cmake. One option is to go to the source
 * directory and create a building subdirectory, using
 * something similar to: <p><tt>mkdir build; cd build; cmake
 * </tt><i>&lt;path to source&gt;</i><p> This starts the build in a
 * created 'build' directory. <p>
 *
 * Depending on what you want from Acquire, you may want
 * to go further than just building an insecure local copy of the
 * software for testing. If this is the case, please use
 * \ref secureinstallexisting or \ref secureinstallown after completing this page.
 * 
 * \subsection buildtest Building a Local Testing Broker with Predefined Keys
 * 
 * If there are any databases existing for either the broker or the
 * client, remove them with: <p><tt>rm ~/.AcquireLib5/*.db
 * ~/.AcquireLib5/*.sql </tt><p> and also in the build directory <tt><p>
 * rm *.db *.sql</tt><p>To build a local broker for testing with
 * predefined keys, <tt>cd</tt> to the '<tt>build</tt>' directory
 * created in the previous section, and invoke the CMake GUI with:
 * <p><tt>ccmake .</tt><p> Press 'c' and then 'g' to generate and exit.
 * Ensure that:<ul> <li>the
 * <tt>DOWNLOAD_NEW_KEYS</tt> option is set to <tt>OFF</tt></li>
 * <li>the <tt>INSECURE_TEST_KEYS</tt> option is set to
 * <tt>ON</tt></li> <li>the <tt>INSECURE_PASSWORDS</tt> option is set
 * to <tt>ON</tt></li> </ul> Then use
 * <p><tt>cmake .</tt><p> to ensure that the required libraries are
 * detected and options are set appropriately.  Then use: <p><tt>make
 * </tt><p> to build an insecure, local system for testing
 * purposes.
 * 
 * \section testing Running Tests with the Local Testing Broker
 * 
 * The
 * local broker tests require that there be an SSH server running on
 * the local machine, with the tester having a valid and accessible
 * user account.  The broker can be started (preferably in a new
 * terminal) using:
 * 
 * <p><tt>./broker</tt><p>
 * 
 * In the local testing mode, the cluster definitions are overridden
 * by the 'test' cluster and no sensitive data can be written to disk.
 * This also
 * implies that any SSH credentials given to the system are temporary
 * as well.  Specifically, a special cluster named
 * 'test' is defined that is accessible through the local machine
 * and can be used
 * to test the broker. It 'queues' your jobs using a python script
 * built to mimic the PBS batch system in use in many clusters for
 * testing the software. While the local broker is running, the
 * interfaces for submitting jobs can be tested as the following
 * sections, \ref tinned_cxx2 and \ref tinned_python2. Of course,
 * these tests can also be carried out with either a remote broker if we
 * have the appropriate keys or a secure broker running locally
 * (both of which can be built via a further process
 * outlined in \ref secureinstallexisting or \ref secureinstallown).
 * 
 * \subsection tinned_cxx2 Initial Testing using the C++ Command Line Interface
 * 
 * This section tests the C++ command line client frontend for the
 * Acquire system. An example workpacket to submit is provided in the
 * '<tt>test_workpacket</tt>' subdirectory in the build directory.  It
 * is assumed that these tests are run from the build directory.
 * 
 * To run a job, first SSH-accessible machines must be added to the
 * system, either to act as gateways or machines on which cluster work
 * queues are accessible. By adding such a machine to a username
 * successfully, a user account is remotely created.
 * 
 * To add a new SSH machine via the C++ interface, use:
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly
 * -n 127.0.0.1 -p 10000 -A</tt><p>
 * 
 * When asked for a hostname use '127.0.0.1' as the 'test' cluster
 * is associated with this machine name. Then type in your local
 * SSH username and password. If this works then you should see a message
 * stating that the machine has been successfully added to Acquire.
 * If you do not see this message try again and ensure that your
 * username and password are correct and that the local SSH server
 * is correctly set up and the credentials you have entered are correct.
 * 
 * A datastore can now be created around a directory that contains the
 * work that you want to run remotely. To create a remote datastore,
 * choose the directory containing the workpacket and upload a
 * description of the data so that the broker can ensure that there is
 * enough space and the data will be secure. This can be achieved
 * using: <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -d
 * ./test_workpacket/ -C</tt><p>
 * 
 * This creates a remote datastore which by default will have the
 * handle '&lt;user&gt;.workdata1', so in this case
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1\'");</script>\endhtmlonly. The view all the actors currently active, use:
 * 
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -T
 * </tt><p> This shows a tree view of the active items. To upload the
 * work data to the newly created
 * datastore, use:
 * 
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -d
 * ./test_workpacket/ -r \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1\'");</script>\endhtmlonly -U</tt><p> This both
 * uploads and marks the data as 'work', prompting the broker to then
 * choose a cluster from those you have made accessible to the system,
 * to which the work is then submitted. Once the work is complete, to
 * get results, one must navigate the job hierarchy again. Use again:
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -T</tt><p>This command
 * gives the status of the work. This should be complete when the
 * 'instance1' child of your workdata has reached the 'finished' state. See
 * that the first workdata has created a child instance, and that that
 * child instance, once complete, has gone on to create another
 * workdata. To download this data, use:<p><tt>mkdir -p
 * \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly; ./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p
 * 10000 -d \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly/ -r
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1.instance1.workdata1\'");</script>\endhtmlonly -D</tt><p> Any data store
 * which you own and have keys for should be downloadable in this way.
 * After successfully downloading the workpacket, in the
 * <tt>\htmlonly<script type="text/javascript">document.write("\'/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly</tt>' directory you should have a
 * file '<tt>work_completed.txt</tt>' which contains a message stating
 * that the test workpacket has been completed.
 * 
 * \subsection tinned_python2 Initial Testing using the Python Command Line Interface
 * 
 * Similarly to the C++ user-facing client, SSH-accessible machines
 * must be added to the system for work to be done. This can instead
 * be achieved by using: <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n
 * 127.0.0.1 -p 10000 -t hello -m &lt;<i>username</i>&gt;@127.0.0.1
 * -A</tt><p> (substituting your username into this command). This adds
 * the SSH login '&lt;username&gt;@127.0.0.1' to the user account
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser2 + "\'");</script>\endhtmlonly on the broker. If the user does not exist, it will be
 * created. The password for the remote account is 'hello' here to
 * expedite batch processing. Once logins to clusters have been added,
 * the upload and submission can be done in a single command:
 * <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -t
 * hello -d ./test_workpacket/ -S</tt><p> Then, as before, the
 * structure can be probed by showing the nodes in the tree
 * structure. <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n 127.0.0.1
 * -p 10000 -t hello -T</tt><p>Finally, downloading the contents of
 * the ultimate child node (the datastore containing results) can be
 * achieved with: <p><tt>mkdir -p \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser2 + "_workpacket_output/");</script>\endhtmlonly;
 * python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -t hello
 * -d \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser2 + "_workpacket_output");</script>\endhtmlonly -r
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser2 + ".workdata1.instance1.workdata1\'");</script>\endhtmlonly -D</tt><p> This download step
 * should be possible with any datastore created.
 * 
 * \subsection automated_python2 Using nosetests
 * 
 * The <i>nosetests</i> program can be instead used to run
 * tests on the system. Find the '<tt>tests</tt>'
 * directory inside the build directory. Edit the file
 * '<tt>test_credentials.py</tt>' to enter your SSH
 * machine, username and password (in this case
 * the machine is 127.0.0.1). Ensure that the broker
 * is running ('<tt>./broker</tt>' in the build directory
 * in a separate window should be fine). Then, in the
 * 'tests' directory, issue the command:
 * <p><tt>PYTHONPATH=.. nosetests</tt><p>
 * The automated tests should then thoroughly test the
 * initial system.
 * 
 * \subsection continuing Continuing with the Build
 * 
 * To secure your newly built broker, continue to \ref secureinstallexisting. */
